## Teach Yourself ActiveX in 21 Days

- Overview
  - The Goal
  - The Standard
- The Technology
- Microsoft NetMeeting
- Let's Get Started
- System Requirements
- The Functions in the API
- Before You Get Started
  - Let's Get To Coding
- The NetConferencing ActiveX Control
  - NetConference API Structures
  - NetConference ActiveX Objects, Properties, Methods, and Events
- Summary
- Q&A
- Workshop
- Quiz

#
— 14 —

##
Programming with the Microsoft ActiveX Conferencing APIs

###
Overview

The Internet has made way for new kinds of communications. The goal is to always make communication as simple as possible, but flexible and full of features. The Microsoft ActiveX Conferencing API is a great new tool because it allows people to participate in conference calls and meetings over their computers.

####
The Goal

The goal of Microsoft ActiveX Conferencing APIs is to allow real-time voice and data communications, application sharing, file-transferring, whiteboard usage (a computer equivalent of using a whiteboard or chalk board in a meeting), and text-based chats. This functionality is nothing new. Each piece or several pieces of Microsoft's ActiveX Conferencing APIs are currently bundled in software by vendors (Microsoft being one of them). You might be wondering why software vendors don't create a single application instead of using one component of Microsoft's ActiveX Conferencing APIs to accomplish one goal; why not create a single application? Unfortunately, applications require a great deal of vendor money and resources, and are often out-dated six months after their release. Many problems related to what I call shrink-wrap software are solved with component software. To make this component software "Internet aware," it must be an Active X product.

####
The Standard

The Microsoft ActiveX Conferencing API and control are based on communications standards governed by an international committee. Many companies are trying to conform to this standard when creating their applications, which means that any other product that conforms to the same standard should be compatible with their product. The Microsoft ActiveX Conferencing API and control are based on standards passed by the International Telecommunications Union (formerly CCITT).

###
The Technology

Underlying conferencing technology are the party host and the party members. The party host manages the party members joining or leaving the conference, and manages how information is transferred to each party member. The party host can be a locator service that lists all people that you can connect with (see Figure 14.6 for an example), or a party host can be you calling your business associate in another town (you would be the party host). An example of this technology is a chat service. Most chat servers operate either as an open room, where anyone can join the discussion, or a private room, where one member specifically invites a newcomer. Everything is centrally managed by the chat server, but made available to anyone that joins.

###
Microsoft NetMeeting

The NetConference APIs and Active X control assume that central host management is handled by another party, namely Microsoft NetMeeting (see Figure 14.1 for user interface of NetMeeting). NetMeeting is the central host and keeps track of who is available to be called or conferenced (see Figure 14.6 for NetMeeting's directory list). NetConference will not install without NetMeeting. Both products are in beta stage as of this writing. NetMeeting has a locator service that sits on a server (probably not your machine). When you install NetMeeting, tell it who and where you are (see Figure 14.5). If you leave your NetMeeting software running in the background, your software lets you know when someone calls you (see Figure 14.2). NetMeeting keeps a list of all NetMeeting users, and acts as an address book that contains NetMeeting contacts. Also, you need NetMeeting because NetConferencing has no way to make a direct connection to necessary protocols. NetConferencing passes requests to NetMeeting, and NetMeeting, in turn, passes the information to the protocols (see Figure 14.3). NetMeeting also allows you to configure audio and compression (see Figure 14.4). It appears that the next release of NetConferening will not require the use of NetMeeting.

Figure 14.1. NetMeeting main user interface.

Figure 14.2. The General property of NetMeeting, which includes your preferences for the handling of incoming calls and files.

Figure 14.3. The Protocols property of NetMeeting allows the user to choose what protocols are available and what protocols he wants NetMeeting to use.

Figure 14.4. The Audio and Compression properties of NetMeeting.

Figure 14.5. Personal information and e-mail information that is available to other members in NetMeeting.

Figure 14.6. This is the directory service listing in NetMeeting.

So if you don't need NetConferencing to manage the host activities, what do you need it for? Simply put, NetConferencing gives you the functionality of one of the members of a conference. And what can a member do? A member can:

- create a new conference and invite someone to join
- call someone else (make a connection)
- request information about a connection
- set information about a connection
- send a file
- send a data stream
- cancel a file or data stream transfer
- activate a remote computer's application
- listen for other calls

###
Let's Get Started

There's a lot to cover about NetConferencing and NetMeeting, including system requirements, the functions in the API, coding issues and other important points.

###
System Requirements

NetConferencing and NetMeeting should work on Windows 95 and Windows NT. At the time of this writing, both products were in beta and only supported on Windows 95. You can get Microsoft NetMeeting and Microsoft NetConference at http://www.microsoft.com/intdev/,which is the Internet Developer page on the Microsoft site. Install the NetMeeting software before installing the NetConference SDK.

###
The Functions in the API

The functions of the API are few at this time, but you can expect more functionality as this product grows. The entire list of APIs follows:

- ConferenceConnect—establishes a conference connection between two systems. This is important because without it, you can't do anything.
- ConferenceDisconnect—stops an existing conference. If you don't end the conference, you will lose system resources.
- ConferenceGetInfo—obtains information about a conference or the users in a conference. The host of the conference might do this to find out information about members and to keep statistics. The members of the conference might do this to find information about specific members.
- ConferenceSetInfo—changes conference settings. Use this function to set either the default directory, where you want to receive files, or the application GUID (special unique identifier) for the application that would be shared between two users.
- ConferenceSetNotify—establishes a notification callback routine for an application. This function lets you assign a function of yours that you want called (the caller is this API) for status information or other notifications.
- ConferenceRemoveNotify—turns off function callbacks for the function set in ConferenceSetNotify.
- ConferenceLaunchRemote—tries to start the application associated with the application GUID. This application does not sit on your machine; rather, it sits on another member of the conference's machine. Use this function to guide that conference member by using his software but letting him see how you are using it.
- ConferenceListen—starts the application on your system so that it listens for calls. The only other way the application can be activated is with an active call.
- ConferenceShareWindow—lets other members of the conference view your window (any object that has a window handle) by passing the window handle to that conference member.
- ConferenceSendData—sends a block of data to the specified members of the conference. This is different from sending a file. Data could be associated with a chat-based conversation.
- ConferenceSendFile—sends a file to the members of the conference. This is different from ConferenceSendData. A file generally has information associated with it that is also sent. Data in a file might include the date of last modification, or read-versus write-capability.
- ConferenceCancelTransfer—stops a file from being transferred. If the process if fast enough, you might not be able to cancel the transfer because might be already finished. This depends on the speed of your machine, the speed of the network, and the speed of the conference members' machines (speed also includes reads and writes to the hard drive).

###
Before You Get Started

You might have noticed that some of the functions have management qualities, such as being able to terminate a conference. How is that possible without a central host?

There are three scenarios

- a first caller terminates the call
- someone that joined in the middle of the conference terminates the call
- the last person to join the conference terminates the call

Assume the last person to join the conference terminates the call. Because he was the last person to join the conference, no other callers or nodes depend on him for their connection. That means there are no side effects from terminating the call.

The middle person, on the other hand, has callers dependent on him. If he terminates, callers that joined after him are terminated by default.

If the first caller terminates, the entire conference is shut down. This seems like a steep condition for a conference call, but it does follow the standard. The standard does allow for the "splitting" of conferences into two, but that is beyond the scope of this chapter.

So now you see why a permanent host is necessary: so the conference never dies. People can join and leave without terminating the conference or being dependent on each other to join.

There are also the concepts of broadcasting and personal connections to other members of the conference. I might want to send my status to my boss only, or I might want to send the network traffic report to everyone in the conference. When sending data or a file, you must specify whether you want the entire conference to receive it, or whether you want an individual member of the conference to receive it.

####
Let's Get To Coding

To use this Conferencing API, include the windows.h and msconf.h header files. You must include the windows.h header file so you can share your applications window; you'll need to be able to pass the window handle.Make sure that msconf.lib is in the path (for library files) for your compiler. The msconf.h and msconf.lib are included in the NetConference SDK (software development kit). The windows.h file should be in your c:\msdev\include directory if you are using Microsoft Visual C++ 4.2. If you don't include the header file or library, NetConferencing will dynamically link to any NetMeeting functionality it needs. Your header files should look something like Listing 14.1. Listing 14.2 is the implementation code for a simple application that connects to a computer, and then disconnects.

> > Hint
> > In Microsoft Windows operating systems, every window has a handle. This handle is used to give the programmer access to the window, yet the programmer doesn't have to know the details of what a handle is. Every object is a window: the desktop, the application interface, even a button. So being able to access the object via its handle is very fundamental to the Microsoft operating systems.

Listing 14.1. Use netconf.h to create header file.

    #include <windows.h> // header file for windows
    #include <msconf.h> // header file for MS NetConferencing

Listing 14.2. Use netconf.cpp to create codefile to connect.

    #include "include netconf.h"
    void main()
    {
     HCONF hconf;
     CONFADDR confAddr;
     CONFINFO confInfo;
    if(CONFERR_SUCCESS == ConferenceConnect(&hconf, &confAddr, &confInfo, NULL))
    {
     if(CONFERR_SUCCESS == ConferenceDisconnect(hconf))
     cout << _T("Connection disconnected successfully") << endl;
     else
     cout << _T("Connection could not be disconnected") << endl;
    }
    else
     cout << _T("Connection could not be established") << endl;
    }

The function ConferenceConnect has the parameters shown in Table 14.1.

> > Note
> > DWORD is a standard in Microsoft Visual C++. Please see the product help files for this and any other data type you don't understand.

> > Hint
> > If you want to see what a user-defined type like DWORD resolves to, make sure your project supports Microsoft Visual C++'s browser information file component. The browser builds a set of data that includes definitions. Make sure your code can compile and build this data. When you are at that stage, right-click the highlighted word DWORD. A pop-up menu will appear, with one of the choices being the definition. Click this to see the definition.

Table 14.1. DWORD WINAPI ConferenceConnect

Parameter | Description
HCONF * phConf | This is the conference handle; without a reference to the handle, you can't access any members or information about the conference.
CONFADDR * lpConfAddr | This is the machine to connect to; it is generally the machine of another member of the conference or the conference host.
CONFINFO * lpConfInfo | This sets the initial information (such as audio and video, and whether you are starting or stopping the conference) for the conference.
CONFNOTIFY * lpConfNotify | This sets information about your call-back function, such as the function address and the application GUID.

Notice that I left the fourth parameter (CONFNOTIFY * lpConfNotify) as NULL, instead of passing a CONFNOTIFY pointer because callback information isn't necessary at this time.

So what do you put in these new data types? The HCONF is a handle to a conference. There can be more than one conference, each identified by its handle, which makes it easy to get to each conference. What is actually inside this variable is not very interesting; it is only important that the other conferencing functions recognize this handle.

The conference address (CONFADDR * lpConfAddr) for the machine is a structure that has a DWORD for the total size of the structure, and a union. The union contains one of two members: the IP address or a character string of the computer name. Which member of the union is used depends on where the union member is assigned (see Table 14.2):

Table 14.2. Assignments and resulting union members.

Assignment | Resulting Union Member
CONF_ADDR_IP | the dword member holds the IP address
CONF_ADDR_MACHINENAME | the string member holds the name of the machine on the local network
CONF_ADDR_PSTN | the string member holds telephone number
CONF_ADDR_UNKNOWN | neither member is used

For a local network, the CONF_ADDR_MACHINENAME computer name(dinaf, for instance) is probably sufficient.

> > Note
> > In this chapter, I use the computer name dinaf as a computer name of another member of the conference. You want to change dinaf to a machine name for another member of the conference.

> > Hint
> > The NetConferencing API takes UNICODE strings. Good macros to brush up on are L"x", _T("x"), where x is a string such as "Joe". Examples are L"Joe" or _T("Joe").

The status code CONFERR_SUCCESS means the function successfully completed its task. Check for this return code on each NetConferencing function. The rest of the return codes appear in Table 14.3. In this table, the word object refers to a file, application or other item. It does not refer to an Active X object.

Table 14.3. NetConferencing function return codes.

Return Code | Definition
CONFERR_ACCESS_DENIED | Access to the object was denied. This usually means you (or whoever) doesn't have permission to perform the operation. This is a system-level event.
CONFERR_ALREADY_SHARED | The application is already being shared. The application can't be shared more than once.
CONFERR_BUFFER_TOO_SMALL | The amount of storage (memory) was too small to handle the request.
CONFERR_ENUM_COMPLETE | The enumeration (itemization) of the requested objects (conferences, members, and so on) is complete.
CONFERR_FILE_NOT_FOUND | The requested file was not found. It either doesn't exist or exists someplace else.
CONFERR_FILE_RECEIVE_ABORT | The transfer of the file was canceled by the receiver.
CONFERR_FILE_SEND_ABORT | The transfer of the file was canceled by the sender.
CONFERR_FILE_TRANSFER | There was a problem transferring the file.
CONFERR_INVALID_ADDRESS | The specified address (machine) was invalid.
CONFERR_INVALID_BUFFER | For some reason, the buffer cannot be read or written to.
CONFERR_INVALID_HCONF | The conference handle is invalid. Be careful. This is a unique identifier that the software creates. Don't mess with it.
CONFERR_INVALID_HWND | The window handle is invalid. Be careful. This is a unique identifier that the operating system creates. Don't mess with it.
CONFERR_INVALID_OPERATION | The request was invalid. There can be several reasons, such as trying to cancel a conference before you have created one.
CONFERR_INVALID_PARAMETER | One of the parameters is incorrect. This could be a variety of things, so check every parameter. If it is computed, check computation.
CONFERR_NO_APP_SHARING | You can't share this application because it is not valid. Be careful what application GUID you set or pass.
CONFERR_NOT_SHARED | The application window is not currently being shared.
CONFERR_NOT_SHAREABLE | You can't share the application window because it is not allowed.
CONFERR_OUT_OUT_MEMORY | There is not enough memory to complete the operation. This is a good indication of a system with memory leaks or without enough resources.
CONFERR_PATH_NOT_FOUND | The path of the object (file, application, and so on) was not found. This could be a reference to a directory or hard drive that is not valid.
CONFERR_RECEIVE_DIR | There is a problem with the directory where the file is to be placed. This could be that the directory doesn't exist or is misspelled.
CONFERR_SUCCESS | The request succeeded completely with no significant errors or problems.

Now that you can connect, let's get information about the conference. Listing 14.3 adds to the code that allows you to connect to a conference.

Listing 14.3. Use netconf.cpp to create codefile to connect to and get information about a conference.

    #include "include netconf.h"
    void main()
    {
     HCONF hconf;
     CONFADDR confAddr;
     CONFINFO confInfo;
    if(CONFERR_SUCCESS == ConferenceConnect(&hconf, &confAddr, &confInfo, NULL))
    {
     if(CONFERR_SUCCESS == ConferenceDisconnect(hconf))
     {
     cout << _T("Connection disconnected successfully") << endl;
     DWORD dwCode;
     VOID vRequestedInfo;
     if(CONFERR_SUCCESS == ConferenceGetInfo(hconf,dwCode,&vRequestedInfo))
     {
     cout << _T("Connection Information retrieved") << endl;
     }
     else
     cout << _T("Connection Information NOT retrieved") << endl;
     }
     else
     cout << _T("Connection could not be disconnected") << endl;
    }
    else
     cout << _T("Connection could not be established") << endl;
    }

The ConferenceGetInfo function has three parameters, which are listed in Table 14.4. The function definition (without parameters) looks like DWORD WINAPI ConferenceGetInfo.

Table 14.4. Parameter information for ConferenceGetInfo.

Parameter | Description
HCONF * phConf | This is the unique conference handle.
DWORD dwCode | This is the type of information you are requesting, such as information on a conference or information on a particular member of the conference.
VOID * pvoid | This is the actual information you requested.

The last two parameters work in unison. The dwCode indicates a type of information. Each kind of information is kept in its own structure. You will need to cast the pvoid to the correct structure to retrieve the information you requested. The first row in Table 14.5 can be understood to mean that if you want to get information about the user, you need to cast the pvoid to a CONFUSERINFO structure, then read the specific members of that structure. For more detail on these structures, refer to the NetConference SDK product specification. The dwCode and void * parameters can be one of the following structures:

Table 14.5. dwCode and pvoid.

dwCode | pvoid
CONF_GET_USER | CONFUSERINFO structure
CONF_ENUM_USER | CONFUSERINFO structure
CONF_GET_CONF | CONFINFO structure
CONF_ENUM_CONF | CONFINFO structure
CONF_ENUM_PEER | CONFDEST structure
CONF_GET_RECDIR | CONFRECDIR structure
CONF_GET_FILEINFO | CONFFILEINFO structure

You might have to fill in part of the structure before casting to a void *, and many of the functions take an all-or-nothing approach. Say, for instance, that you want information on either one user or on all users; placing a zero in the appropriate field of the structure indicates that you are requesting information on all users. See the end of this chapter of a listing of each structure.

> > Hint
> > The specification has types like LPCONFDEST and LPCTSTR. LP refers to a local pointer, and the data type LPCONFDEST is usually #defined like this:
> > #define LPCONFDEST CONFDEST *

###
The NetConferencing ActiveX Control

The NetConferencing ActiveX control is another way to access a conference. The ActiveX control dynamic link library is IMSCONF.DLL. The NetConferencing ActiveX control can be used like any other, meaning it can be used in an HTML document or a script (such as VBScript or JavaScript). The control sits on top of the MSCONF.DLL (SCRAPI, using the xxxAPI naming convention, such as MAPI or TAPI).SCRAPI is the codename for the API technology.

> > Hint
> > Some of the methods return a BSTR. A BSTR is a specific system string type in OLE. A BSTR is a CHAR *, but the type holds its count of characters after the string. Don't try to manipulate BSTRs yourself. OLE provides several functions: SysAllocString, SysAllocStringLen, SysFreeString, SysReAllocString, SysReAllocStringLen, and SysStringLen. There is a certain amount of bytes cached by OLE, so when you do the final SysFreeString on a variable, you won't see the memory freed. Don't worry. OLE has some built-in memory cache and BSTRs are included.

The objects in the Active X control are the conference manager, user, conference, member, and channel. A conference manager is the host that I referred to in the beginning of this chapter. The user is any potential member of a conference; this could be someone who has the NetMeeting software running in the background listening for a call. A conference is exactly what it sounds like. A member is an active participant in the conference. The channel is media-specific pipe for communicating, such as an audio channel or a video channel. If you have put stereo equipment together, the channel should be a familiar concept. For the first beta release of NetMeeting, four channels are supported: data transfer, file transfer, application sharing, and application control. The audio and video channels will be supplied in future releases. The channel control doesn't always support the user-to-user concept in each method, and the default behavior is a broadcast message to everyone in the conference. Check each method call in the SDK for broadcast versus peer-to-peer connection information.

Let's write a Web page that uses this NetConference ActiveX control . You need a Window_OnLoad subprocedure to get things started, and a Window_OnUnload subprocedure to get things cleaned up. You also need a text box to show user names in the conference, and two buttons, one to join the conference and one to leave the conference, and procedures for these buttons. Listing 14.4. shows the HTML for the text box, buttons, and procedures. Figure 14.5. illustrates how the Web page looks in the Microsoft Internet Explorer 3.0 browser.

Listing 14.4. Use conf.htm to configure VBScript to use the NetConference ActiveX control .

    <HTML>
     <HEAD>
     <TITLE> NetConference ActiveX Sample </TITLE>
     </HEAD>
     <BODY>
     <CENTER>
     <H1> NetConference ActiveX Sample </H1>
     </CENTER>
     <HR>
     <B> Members of conference: </B>
     <BR>
     <PRE><TEXTAREA NAME = MyTextBox COLS = 80 ROWS = 10></TEXTAREA></PRE>
     <PRE>
     <INPUT NAME=Join TYPE=BUTTON VALUE="Join">
     <INPUT NAME=Leave TYPE=BUTTON VALUE="Leave">
     </PRE>
    <!-- Here the is NetConference ActiveX control -->
    <OBJECT
     ID = ConfMgr
     CLASSID="clsid:53D22820-D7E8-11CF-ADOA-0080C7137C82">
    </OBJECT>
    <SCRIPT LANGUAGE="VBScript">
    Option Explicit
    Dim Conference <!-- Global Conference Object -->
    Sub Window_OnLoad
     <!-- Window_OnLoad code goes here -->
    End Sub
    Sub Window_OnUnload
     <!-- Window_OnUnload code goes here -->
    End Sub
    Sub Join_onClick()
     <!-- Window_OnLoad code goes here -->
    End Sub
    Sub Leave_onClick()
     <!-- Window_OnLoad code goes here -->
    End Sub
    </SCRIPT> </HTML>

Now that you have the basic code, add code to create and delete the conference, and to join or leave the conference. Notice in Listing 14.4 that you created your conference manager object (variable: ConfMgr) and conference object (variable: Conference). Because they are not declared in a subprocedure, they are global to the script and can be accessed by any subprocedure in the script.

To initialize the Active X control , add Listing 14.5 to the Window_OnLoad subprocedure. In Listing 14.5, you create a conference collection object (variable: Conferences) because there can be many conferences running simultaneously. After you declare your variables, initialize your conference manager object. Pass the GUID of the calling application, then go through the conference collection and grab the first one you find. If there are members already in the conference, add them to the text box. The ConfMgr.Advise and Conference.Advise variables let the ActiveX control listen for notifications.

Listing 14.5. Add the Window_OnLoad code to conf.htm .

    Sub Window_OnLoad
     Dim Conferences 'Conference collection
     Set Conference = Nothing
     On Error Resume Next
     If Not ConfMgr.Initialize
     [ ]("{00021191-0000-0000-C000-000000000046}") Then
     MsgBox "Can't Initialize Conference Manager !!!"
     Exit Sub
     End If
     ConfMgr.Advise
     Set Conferences = ConfMgr.Conferences
     If Not(Conferences Is Nothing) Then
     'Get first conference in conference collection
     Set Conference = Conferences(0)
     If Not (Conference Is Nothing) Then
     Conference.Advise
     'GetCurrent Members in the first conference
     Dim Members
     Dim ThisMember
     Dim arrayIndex
     If Members Is Nothing Then
     MyTextBox.Value = "Error" & Hex(Err.Number)
     Else
     MyTextBox.Value = "" 'Initialize text box
     For arrayIndex = 0 To Members.Count -1
     MyTextBox.Value = MyTextBox.Value &  Members(arrayIndex).Name & Chr(13) & Chr(10)
     Next
     End If
     End If
     End If
    End Sub

Listing 14.6. adds the cleanup code you need. Because you have opened a conference and a conference manager, it makes sense that you would have to close them down. There is no need to clean up the text box, but it is a nice thing to do for users of the Web page.

Listing 14.6. Add the Window_OnUnload code to conf.htm .

    Sub Window_OnUnload
     MyTextBox.Value = "" <!-- Make the text box have no names, ie blank à
     If Not (Conference Is Nothing) Then
     Conference.Unadvise
     Set Conference = Nothing
     End If
     ConfMgr.Unadvise
     ConfMgr.Uninitialize
    End Sub

Listing 14.7. adds the code you need to join the conference. Notice that if a conference was not previously created, you create one here. Then you create a user and invite the user to join in the conference. The user in this case is a computer name. You would want to enter the correct name in place of MyMachineNameOrIPAddress. After a user joins a conference, he changes from a user to a member. At this point, you want to reassemble all the members of the conference and put all their in the text box. The code to do this is presented in Listing 14.7.

Listing 14.7. Add the Join code to conf.htm .

    Sub Join_onClick
     Dim User
     On Error Resume Next
     If Conference Is Nothing Then
     <!-- Create the conference if it doesn't exist (1 means a data conference) à
     Set Conference = ConfMgr.CreateConference("MyConference",1)
     If Conference Is Nothing Then
     MsgBox "Couldn't create conference"
     Exit Sub
     End If
     Conference.Advise
     End If
     <!-- Create the user if it doesn't exist (2 means machine name)à
     Set User = ConfMgr.CreateUser("MyMachineNameOrIPAddress",2)
     If User Is Nothing Then
     MsgBox "Couldn't create user "
     Else
     If Not Conference.Invite(User) Then
     MsgBox "Couldn't invite user"
     End If
     End If

To do the necessary cleanup, we need some code to handle when we close the browser or leave this page to load another. So the Leave code is fairly straight-forward, as Listing 14.8 illustrates.

Listing 14.8. Add the Leave code to conf.htm .

    Sub Leave_onClick
     On Error Resume Next
     If Conference Is Nothing Then
     MsgBox "Conference isn't active"
     Else
     If Not Conference.Leave Then
     MsgBox "Couldn't leave conference"
     End If
    End Sub

To use a conference in this ActiveX control , you must create a conference object, but you only need one per application instance. You can create the other objects by having a method return that object as instantiated (User, Conference, Communication Channel and File Transfer) or by having an enumeration create that object (Member, Client Application, Shareable Application). For a list of objects, please refer to the end of this chapter.

When you attempt to open this page in your Internet Explorer 3.0, you will notice a message box (see Figure 14.7) asking you whether you want to activate the control. This is a nice way for the user to be aware that something is going on with his computer, and to have a degree of control over it.

Figure 14.7. NetConference asks you how you would like to use it.

NetConference will be very useful in scripts. Imagine that you go to a conference HTML page. You find a list of people involved in the conference, a text box for you to enter a message to send, and a text box for you to read messages as they are entered by other members of the conference. Joining a conference is as simple as clicking a button on an HTML page! For complete information on this control, refer to the specification you will get when you download and install the SDK.

####
NetConference API Structures

All dwSize variables are the size of the structure in bytes. When you look at the API parameters in more detail, remember that you might have to pass the size or count of an object.

> > Hint
> > When dealing with string characters, a variable can refer to the count of characters or the count of bytes. This is important when dealing with any character that is larger than one byte. Most API function parameters expect count of bytes, regardless of data type, but it is important to check anyway. The parameter cb refers to count of bytes.

Table 14.6 contains the structure members for the CONFUSERINFO structure.

Table 14.6. Specification: the structure CONFUSERINFO members .

Member | Description
DWORD dwSize | size of this entire structure
DWORD dwUserID | unique value for user in conference
DWORD dwFlags | combination of: CONF_UF_DATA user is in a data conference CONF_UF_AUDIO user is in a audio conference CONF_UF_VIDEO user is displaying a video image CONF_UF_LOCAL indicates a local user
DWORD dwReserved | reserved for future use, must be 0
DWORD szUserName | null terminated string of user's name

Table 14.7 contains the members of the CONFINFO structure.

Table 14.7. Specification: the structure of CONFINFO members .

Member | Definition
DWORD dwSize | size of this entire structure
HCONF hconf | conference handle
DWORD dwMediaType | combination of: CONF_MT_DATA data conference CONF_MT_AUDIO audio conference CONF_MT_STOPPING stopping the conference
DWORD dwState | current conference state, combination of: CONF_CS_INVALID state of conference is invalid CONF_CS_INITIALIZING state of conference is initialized CONF_CS_ACTIVE state of conference is active CONF_CS_STOPPING state of conference is stopped
DWORD cUsers | number of people in conference
DWORD dwGCCID | GCC identifier
DWORD szConferenceName | null-terminated name of conference
[CONF_MAX_CONFERENCENAME] |

CONF_MAX_CONFERENCENAME refers to a constant number defined for the maximum characters in a conference name.

Table 14.8 contains the members of the CONFDEST structure.

Table 14.8. Specification: the structure of CONFDEST members .

Member | Description
DWORD dwSize | size of this entire structure
DWORD dwFlags | destination flags for transfer, when receiving CONFN_DATA_SENT or CONFNDATA_RECEIVED notifications; combination of: CONF_DF_BROADCAST data sent to everyone CONF_DF_PRIVATE data send to one person CONF_DF_DATA_SEGMENT_BEGIN start of data CONF_DF_DATA_SEGMENT_END end of data
DWORD dwUserId | specific person or 0 (0 represents broadcast)
DWORD dwReserved | application GUID or 0 (0 represents it does not apply)

Table 14.9 contains the members of the CONFRECFIR structure.

Table 14.9. Specification: the structure of CONFRECDIR members .

Member | Description
DWORD dwSize | size of this entire structure
TCHAR szRecDir[MAX_PATH] | full path of default directory for received files

MAX_PATH refers to the constant number defined for the maximum number of characters for this string.

Table 14.10 contains the members of the CONFFILEINFO structure.

Table 14.10. Specification: the structure of CONFFILEINFO members .

Member | Description
DWORD dwSize | size of this entire structure
DWORD dwFileID | unique file ID
DWORD dwReserved1 | reserved for later use
DWORD dwFileSize | size of the file in bytes
DWORD dwReserved2 | reserved for later use
DWORD dwBytesTransferred | count of bytes transferred
DWORD dwFileAttributes | file attributes such as read, archive, hidden, or system
FILETIME ftCreationTime | time the file was created
FILETIME ftLastAccessTime | last time the file was opened
FILETIME ftLastWriteTime | last time the file was modified
TCHAR szFileNameSrc[MAX_PATH] | name of the original file
TCHAR szFileNameDest | name of the file as it is put in the receiving directory

MAX_PATH refers to the maximum number of characters that can be in the string szFileNameSrc.

####
NetConference ActiveX Objects, Properties, Methods, and Events

NetConference ActiveX Objects are: Conference Manager, User, Conference, Member, and Communication Channel. Remember that properties are information about the object such as what the text is in a text box. A method acts on the object such as capitalizing all characters in a text box. An event is a piece of code that does something when a specific event happens such as when I click the text box to change it, all characters in the text box are automatically highlighted. Table 14.11 is a list of properties, methods, and events for the IConferenceManagerX object .

Table 14.11. IConferenceManagerX properties , methods, and events.

Properties | Methods | Events
ConferenceCapabilities | Initialize | InvitedToConference
RemoteConference | Uninitialize | ConferenceCreated
Conferences | CreateConference | StateChanged
Users | CreateUser | RequestToJoin
NullObject | Advise | MemberChanged
| Unadvise | InvitedToConference
|  | ConferenceCreated
|  | StateChanged
|  | RequestToJoin
|  | MemberChanged
|  | ChannelChanged
|  | DataSent
|  | DataReceived
|  | FileSent
|  | FileReceived
|  | AppSharingStatusChanged
|  | AppControlStatusChanged

Table 14.12 is the list of properties for the IConfUserX object. This object has no events or methods.

Table 14.12. IConfUserX properties (no events or methods).

Properties
Name
Type
ConferenceCapabilities
IsMCU
Conferences
Applications

Table 14.13 is the list of IConferenceX properties and methods. This object has no events.

Table 14.13. IConferenceX properties and methods (no events).

Properties | Methods
Name | Invite
Capabilities | AcceptInvite
State | RejectInvite
Members | Join
Applications | AcceptJoin
ChannelInterfaces | RejectJoin
Channels | CreateChannel
| Leave
| IsSameAs
| Advise
| Unadvise

Table 14.14 is a list of IConfMemberX object's properties and methods. This object has no events.

Table 14.14. IConfMemberX properties and methods (no events).

Properties | Methods
Name | IsSameAs
Type |
ConferenceCapabilities |
IsMCU |
Conferences |
Applications |
Conference |
IsSelf |

Table 14.15 is a list of IConfChannelX's properties and methods. This object has no events.

Table 14.15. IConfChannelX properties and methods (no events).

Properties | Methods
Conference | IncludeMember
Interface | ExcludeMember
Members | IsSameAs
Objects |

Table 14.16 is a list of IconfDataExchangeX methods. This object has no properties or events.

Table 14.16. IConfDataExchangeX methods (no properties or events).

Methods
SendData
Advise
Unadvise

Table 14.17 is a list of IConfFileExchangeX properties and methods. This object has no events.

Table 14.17. IConfFileExchangeX properties and methods (no events).

Properties | Methods
ReceiveFileDir | SendFile
| Cancel
| Advise
| Unadvise

Table 14.18 is a list of IConfAppSharingX properties and methods. This object has no events.

Table 14.18. IConfAppSharingX properties and methods (no events).

Properties | Methods
SharableApps | Advise
| Unadvise

Table 14.19 is a list of IConfAppControlX methods. This object has no properties or events.

Table 14.19. IConfAppControlX methods (no properties or events).

Methods
StartRemoteInstance
Advise
Unadvise

Table 14.20 is a list of IConfApplicationX properties. This object has no events or methods.

Table 14.20. IConfApplicationX properties (no events or methods).

Properties
GUID
Name

Table 14.21 is a list of IConfShareAppX properties and methods. This object has no events.

Table 14.21. IConfShareAppX properties and methods (no events).

Properties | Methods
Name | Share
ShareState | Unshare

Table 14.22 is a list of IConferenceX properties. This object has no events or methods.

Table 14.22. IConferenceX properties (no events or methods).

Properties
BytesTransferred
String
Array

Table 14.23 is a list of IConfFileTransferX properties and methods. This object has no events.

Table 14.23. IConfFileTransferX properties and methods (no events).

Properties | Methods
Name | IsSameAs
BytesTransferred |
TotalSize |
State |

###
Summary

The NetConferencing APIs and the NetConferencing ActiveX control extract the know-how from the programmer while leaving a great deal of functionality for the user. This functionality is not for the timid. The product is in its earliest stages, and a great deal remains to be fleshed out.

This software allows an application (Web page or windows GUI interface) to let people join a conference, transfer data or files, and disconnect from the conference. Conference management functionality is also included, but you must depend on NetMeeting to make this software work.

###
Q&A

- Q Where do you get the NetConferencing and NetMeeting software?
- A http://www.microsoft.com/intdev/. This is the Internet developer studio on the Microsoft site.
- Q What do NetConferencing and NetMeeting give you?
- A The capability to have multiway conferencing through your Internet browser or other applications.
- Q What are the system requirements?
  A For beta release: Win95
  For product release: WinNT and Win95
- Q What is the main object in the NetConference ActiveX control?
- A conference manager

###
Workshop

Develop a cool application or Web page that uses NetConference to transfer data and files between your computer and someone else's computer.

###
Quiz

> > Note

> > Refer to the Appendix, "Answers to Quiz Questions," for the answers to these questions.

1. What is the difference between a conference manager and a conference?
2. What is the difference between a user and a member?
3. What software is a requirement of NetConference?